feat!: GitOps Reverser decides when Flux or Argo CD applies a folder - #419

…on triggers

The ask filters the reconciler's webhook so our own pushes stop waking it.
That is not enough: Argo CD's timed refresh resolves the tip, and with
selfHeal off a new revision still auto-syncs, so every push of ours is
applied two to three minutes later over whatever is still pending. Flux
applies on every reconcile, whatever woke it.

So the reconcilers keep fetching, rendering and applying, but apply only
when we ask: Argo CD without automated sync and a sync pinned to the
checked revision, Flux through its Receiver with long intervals. The
response also records where the ask's rule needs correcting (empty refusal
commits, the replayed push, per-cluster suppression), the branch-worker
state that replaces per-delivery classification, and what changes for
gitops-api and in this repository.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

… code

Docs-first, for review: the guides now read as they will once GitOps
Reverser decides when Flux or Argo CD applies a folder.

- A GitTarget names its applier (spec.applier: kustomizationRef,
  applicationRef or webhook). Requests go out only on a quiet branch,
  for a foreign commit, an eligible refusal, or, for Flux, a CatchUp
  that keeps its artifact current after our own pushes.
- Argo CD runs with automated.enabled: false, and our sync copies the
  operation its automated sync would build, pinned to the checked commit.
- GitProvider.spec.receiver takes the Git host's push webhook on its own
  listener; a delivery is a hint judged against the ref advertisement.
- onRefusal: PushEmptyCommit becomes onRefusal: Reapply.
- definitions.md gains applier, apply request, quiet branch and receiver.

The push-notification design drops its options menu for the decided
design, and the reply to gitops-api's ask is aligned with it. The
generated settings table is untouched until the CRDs change.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…d prove the revert was requested

The seeded root commit has no parent to diff against and reads as empty, so
the spec now compares against the count before the GitTarget exists. It also
asserts the GitTarget's ApplyRequested Event names Refusal, so the revert is
shown to come from GitOps Reverser's request rather than Flux's own schedule.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…rite

The bi-directional e2e reproduced the race the trigger exists to prevent. A
window with a zero idle timeout opened, closed, committed and pushed inside
one wake that ended quiet, so the quiet period was inherited from the quiet
wakes before it and the catch-up went out at once. Flux applied that commit
over the next API edit, and the revert was mirrored as Flux's commit.

Deciding a write now restarts the quiet period wherever in the wake it
happens, so a catch-up waits quietPeriod from the last write.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

What comes after the Flux applier: the Argo CD applier and how to build it,
the PushEmptyCommit regression for appliers GitOps Reverser cannot name, the
smaller loose ends, and the parts of the trigger the tests do not reach yet.
The index entry for the trigger design now describes it as built for Flux.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

A delivery waits on the worker's queue behind an in-flight push rather than
being compared against a recorded in-flight commit; the foreign-commit test
compares against the last observed tip; a Flux request stamps the
GitRepository or the Kustomization, not both; the SourceMismatch example
uses the real message; and the receiver's Helm default is empty.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Record the 2026-10-16 review's six findings and their shared cause (a
request decided once is never checked again at the patch), the fix for
each, and the hand-back that replaces giving up on a failed request.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

The worker decided a request once, and the dispatcher attempted it for up
to four minutes against whatever the cluster, the GitTarget and the branch
had become. Every attempt now reads each GitTarget again and keeps only
those that still name the applier on this branch and that their
ClusterProvider admits; a Refusal needs consent at the attempt, and a
target that withdrew it is asked a CatchUp. Flux.Request checks the
GitRepository's repository and branch before it stamps anything.

A request that cannot be delivered is retried for about one quiet period,
then handed back to the branch worker, which owes it again and sends it on
a quiet branch with its own backoff. A refusal owed while the branch was
busy is checked for consent again before it is sent, and a collection that
recovers cancels its own obligation. The applier check runs under a
deadline, and the chart's Flux role drops list and watch.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

A Refusal asks one applier, but a GitRepository that has to fetch the tip
wakes every Kustomization that reads it; say so in the five places that
promised no other folder is woken. Document the per-attempt checks and the
hand-back, the dropped outcome, the upgrade order the old CRD allows, and
the access-review permission.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

The ledger behind status.applier was keyed by namespace and name and never
pruned, so a GitTarget deleted and recreated under the same name inherited
its predecessor's last request. It now remembers the uid it recorded for,
and the GitTarget controller forgets an entry when the object is gone.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

A Kustomization whose GitRepository follows another branch is reported
SourceMismatch, a ForeignCommit for it never stamps that source, and the
request is delivered once the source is fixed. A real Gitea push webhook to
the operator's receiver Service makes Flux apply a Git-side push with
nothing else on the branch. A unit test covers a second write inside the
quiet period.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

With no receiver and no API edit, an idle GitTarget's steady-tick refresh
finds an outside push, and Flux applies it from a ForeignCommit request:
a missing webhook costs latency, never an apply.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/flux.md is the complete Flux setup: why the GitRepository must not
fetch on its own, a worked example, the rules ApplierConfigured checks,
permissions, the Git host's webhook, what a request does and that it is
asynchronous, how to check it works, troubleshooting, and which test
proves each claim.

A unit test reads the guide's complete example and checks it against the
applier: the objects decode with no unknown field, ApplierConfigured comes
out True, a request stamps the GitRepository, and the Flux objects follow
the page's own advice. The bi-directional guide's Flux section now points
to it, and the chart's applierAccess comment matches the role.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

The second review found every remaining problem in the hand-off between
the worker's decisions and the dispatcher's retries: a retry skipped the
quiet check, outlived a refusal that had recovered, ran for a recreated
GitTarget, or waited on another applier's branch-wide backoff.

The dispatcher now carries out one attempt and reports back. It keeps no
queue, never retries, and never asks for something weaker than it was told:
when no GitTarget still holds the request's reason it asks nothing. The
worker keeps what each applier is owed, one attempt out at a time, with the
applier's own backoff, and decides every retry on a quiet branch at the tip
as it is then, giving back a refusal only while it still stands. Requests
carry each GitTarget's uid, and an obligation owed to an incarnation that is
gone is dropped.

The three relations get their own units: the branch (repository and branch,
shared across workers of different GitProviders) owns quietness, the applier
owns obligations and retries, the GitTarget owns consent. A shared
Kustomization is asked once and waits for the longest quiet period of the
GitTargets naming it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

The bi-directional corner proved that a new GitRepository revision alone
makes a Kustomization apply by pushing an empty commit. It now pushes a
commit that changes only a file outside the applied folder, which proves
the same property without the trick. Code and test comments cite the new
apply trigger design, or the archived one for the Git-side reference.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/design/apply-trigger.md replaces the trigger design (now archived in
docs/finished/) with why GitOps Reverser decides when Git is applied, what
building it taught, the three units that make the 1:n cases work, the
apply window that is still racy and how to shrink it, and the aim beyond
Flux. The follow-ups page and gitops-api's original ask are removed.

architecture.md and configuration.md state the aim again (Argo CD with a
pinned sync and no catch-up, a webhook applier) beside what is built, and
describe the worker-owned obligations. The refusal empty commit is gone
from the design docs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

An attempt decided at one commit could land after the worker pushed a newer
one and, finding the artifact at the older commit, stamp the Kustomization,
re-applying it over a published edit. A request now carries a check the
dispatcher makes just before it stamps: the commit is still the branch tip
and nothing is waiting to be published, on this worker or a sibling. When
it fails nothing is stamped (Stale), and the worker decides again at the
next quiet moment, with no backoff. A ForeignCommit whose artifact already
holds the commit stamps nothing: that artifact already woke the
Kustomization. Only a Refusal stamps the Kustomization, to revert drift at
an unchanged commit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

A push notice that reached a busy branch always closed the open window, so
the Git host's late webhook for the worker's own push cut the next save's
window, splitting that save across two commits. A notice naming the tip
already observed now leaves the window alone; anything else still closes
it. The delivery's after is still never trusted as the tip, and leaving a
window open is the safe direction: it closes on its timers, and its push
finds any move by the compare-and-swap.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

GitHub's default content type for a webhook wraps the JSON in a payload
field, so a hook left on that default got a 400 on every push, while a Flux
Receiver accepts it. The signature is over the raw body, so the payload is
unwrapped only after verification. The flag help no longer promises an
elected replica: leader election is not switched on, and the chart runs one.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Document that only a Refusal stamps a Kustomization whose artifact holds
the commit, that a stale decision stamps nothing, and the stale outcome.
The apply trigger design gains its roadmap, with the customer review's
remaining items: the applier in the GitTarget's own cluster, receiver
hardening, closing the apply window's loop, Argo CD, the webhook applier,
and more than one replica. The Flux guide notes that a namespace Role is
enough. The e2e recovery assertion checks that Flux reaches the tip, since
whether the retry or Flux's own fetch gets there first is a race.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

spec.applier.clusterProviderRef names the ClusterProvider whose cluster
holds the Kustomization; omitted, it is the GitTarget's own
spec.clusterProviderRef, so nothing that exists changes meaning. It covers
Flux run from a management cluster (gitops-api's kcp workspaces, every
hub-and-spoke install), which used to sit at ApplierNotFound forever, and it
is the shape the Argo CD applier will take for a hub Argo CD.

The applier's provider is gated exactly as a source's is: its accessFrom must
admit the GitTarget's namespace (authz.ApplierAdmitted), checked by
ApplierConfigured and again by the dispatcher before every attempt. A
ClusterProvider change re-checks the GitTargets using it as an applier's.

An applier-only cluster has no cluster context, because nothing would
release one: ApplierDynamicClient reuses a mirrored cluster's client, and
otherwise builds one per call from the provider as it resolves.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

An apply runs a few seconds after its stamp. An API edit in those seconds,
to a field the Kustomization applies, was reverted by the apply and mirrored
as Flux's commit, so the edit survived only in history. For an object both
sides changed the API value wins; this applies that rule to the apply
window.

The window is now known: the dispatcher reports a delivered attempt only
once Flux finished it (lastHandledReconcileAt carries the stamp, or the
Kustomization attempted a new revision after a source stamp), at most 5
minutes, and the worker keeps it open 10 seconds more for the watch.

Inside it, a write whose latest managedFields entry is kustomize-controller
alone, to an object in the applier's folders that the API side edited after
the attempt was sent, is withheld. Git keeps the edit and the CatchUp its
push owes applies it back. Only proof withholds: a same-second tie with
another manager could be the edit itself and is mirrored as before, and a
DELETE never is. Every collision is logged and counted in
apply_window_collisions_total{outcome="withheld"|"ambiguous"}.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…e standard

GitOps Reverser takes full control of when Argo CD syncs: an Application a
GitTarget names has automated sync off, and every sync is one GitOps
Reverser asked for, pinned to a commit it checked. The plan records the
upstream facts it rests on (argocd-controller is the field manager for
client-side and server-side apply alike, the operation autosync builds,
never replacing a running operation, sync windows apply to every
operation), what to build, the tests, and three open questions: where
prune comes from, the operation's initiator, and hooks on every foreign
commit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Prune from automated.prune when the block is kept with enabled: false,
the initiator Automated: true as gitops-reverser, and hooks on every
foreign commit shipped as they are. Built on #419's branch.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

spec.applier gains applicationRef beside kustomizationRef, exactly one of
the two (CEL). quietPeriod times the CatchUp, and Argo CD is never asked to
catch up, so it is rejected with an applicationRef; it loses its schema
default for that reason, and an omitted one still means 30s.

The branch worker keys an applier by its kind as well as its cluster,
namespace and name. An Application is never owed a CatchUp: with automated
sync off it applies nothing on its own, so nothing it holds goes stale.
ForeignCommit and Refusal reach it as they reach a Kustomization. The apply
window knows each kind's own field managers: kustomize-controller for Flux,
argocd-controller and argocd-application-controller for Argo CD.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

… checked

The Argo CD client sets the Application's operation to the sync automated
sync would start (source, prune from syncPolicy.automated, syncOptions and
retry from syncPolicy), with the revision pinned to the commit and
initiatedBy {username: gitops-reverser, automated: true}. It is an update of
the whole Application, as Argo CD's SetAppOperation makes it, guarded by the
resourceVersion read, and it clears status.operationState. An operation
already running is waited out (up to the apply window) and never replaced;
an update that lost a race reads again and decides again.

Two places differ from what was planned, each read from Argo CD's source: a
failed operation awaiting its retry is Running with a finishedAt, so a sync
counts as finished only once its phase is Succeeded, Failed or Error; and a
retry with refresh: true drops the pinned revision, so the copied retry
omits it. The request's token travels in operation.info.

The dispatcher picks Flux or Argo CD by the applier's kind behind one Client
(Validate, Request, Handled), so an attempt and its wait for the applier are
unchanged; apply_requests_total counts applier_kind="application".

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…ent it

ApplierConfigured checks the applier by its kind: an Application must exist,
sync this repository and branch from a single source (targetRevision the
branch name or refs/heads/<branch>), have automated sync off, and be
updatable. Automated sync on is the new AutomatedSyncEnabled reason, which
stalls the GitTarget like the other configuration errors.

RBAC: config/rbac/argocd-applier-role.yaml and the chart's
applierAccess.argocd grant get and update on argoproj.io applications, off
by default in the chart, beside the Flux grant.

docs/argocd.md is the Argo CD guide, with the standard spelled out
(automated sync off; refresh and Argo CD's webhook may stay) and its
complete example held to the code by argocd_guide_test.go. The
configuration reference, the bi-directional guide, the support boundary,
the metrics guide and UPGRADING describe the Application applier, and
apply-trigger.md takes what lasts of the implementation plan, which is
deleted.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…c off

The Argo CD specs now run the standard: the Application has automated sync
off and is named by spec.applier.applicationRef, and its GitProvider has a
receiver Gitea pushes to. They prove that a Git-side push is synced by a
ForeignCommit request pinned to that commit (and Argo CD's bookkeeping still
makes no commit); that two quick API edits keep the later value with no
further commit and no sync; that a refused edit with onRefusal: Reapply is
reverted by an Argo CD sync; and that an Application with automated sync on
is AutomatedSyncEnabled, stalls its GitTarget, and is never synced by
GitOps Reverser.

The phases that characterized automated sync (selfHeal losing an edit,
ignoreDifferences, selfHeal: false with Argo CD's webhook) are gone with
it. Argo CD's webhook stays wired, and is shown only to refresh. The receiver
wiring is shared with the Flux applier spec.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

status.applier and the applier check are published on the GitTarget's
reconcile, and a delivered request does not trigger one, so a converged
target can take minutes to show it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>